Document upstream visibility enum + cascade for advanced/hidden flags#182
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation update to clarify the upstream (ESPHome) source-of-truth for the ConfigEntry.advanced and ConfigEntry.hidden flags, so future maintainers understand these values come from schema annotations rather than frontend-side heuristics.
Changes:
- Expanded
ConfigEntry.advancedJSDoc to point to ESPHome’scv.Optional(..., advanced=True)annotation as the authoritative source. - Expanded
ConfigEntry.hiddenJSDoc to point to ESPHome’scv.Optional(..., yaml_only=True)annotation and explain the intended UX behavior.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
16 tasks
bdraco
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Multi-line backticked spans render poorly in TS-tooling hovers (VS Code in particular). Shorten the references to bare `Visibility.ADVANCED` / `Visibility.YAML_ONLY` so each inline- code span sits on a single line.
Two follow-ups on the JSDoc Copilot flagged: * Cascade references used a bare ``ADVANCED`` / ``YAML_ONLY`` token after the first ``Visibility.ADVANCED`` / ``Visibility.YAML_ONLY`` mention. Bare tokens read as frontend-local concepts; qualified with the enum prefix they read as the upstream marker being cascaded. Switch both trailing references to the qualified form. * ``upstream esphome's`` → ``upstream ESPHome's`` for capitalisation consistency with the rest of the file. Drive-by: replace the inline em-dash in the ``hidden`` JSDoc with a semicolon, matching the project's no-em-dash convention in prose. No content change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this implement/fix?
Documentation pass on the
ConfigEntry.advanced/ConfigEntry.hiddenTypeScript types, calling out that the authoritative source for those flags is upstream ESPHome's newcv.Visibilityschema kwarg (esphome/esphome#16267, merged into 2026.5.0b1); not the hand-curated heuristic in the catalog generator. Also notes the cascade pass added to the catalog generator (esphome/device-builder#350): a stricter parent forces every descendant at-least as strict, so a child'shidden=truemay have arrived from an ancestor'sVisibility.YAML_ONLYrather than from the field's own schema marker.The upstream PR ships two real fields marked in 2026.5.0b1:
setup_priorityon every component (Visibility.YAML_ONLY); the time platform'supdate_interval(Visibility.ADVANCED). The frontend already filtersentry.hiddencorrectly (isEntryVisibleinsrc/util/config-validation.ts) and rendersentry.advancedunder the disclosure (config-entry-render-filter.ts), so no runtime change is needed; the next catalog sync against a schema bundle containing #16267 (https://schema.esphome.io still pins 2026.4.5 today) is what threads the new schema values onto those existing fields.This PR exists so the frontend type docstrings explicitly point future maintainers at the upstream source. As upstream adoption of the new kwarg grows, the catalog's heuristic fallback shrinks; readers of the frontend code shouldn't have to trace through the catalog generator to figure out where
entry.advancedwas decided.Related issue or feature (if applicable):
Types of changes
bugfixnew-featureenhancementbreaking-changerefactordocsmaintenancecidependenciesChecklist
npm run lintpasses.npm run testpasses (1034/1034).